headlamp-plugin: opt-in Claude Code agent harness (--with-claude-skills)

What

Adds an opt-in --with-claude-skills flag to headlamp-plugin create and
headlamp-plugin upgrade that scaffolds a Claude Code agent harness for
building a Headlamp plugin with an AI agent.

The harness:

• CLAUDE.md — always-on agent policy (replaces the default AGENTS.md)
• .claude/skills/ — the CNCF/CRD plugin workflow: create-cncf-plugin,
  plan-plugin, define-resource, add-list-view, add-detail-view,
  add-settings, ensure-dependency, seed-test-data, run-and-verify,
  document-plugin
• .claude/settings.json — permission allowlist for common dev commands
• .mcp.json — kubernetes, helm and chrome-devtools MCP servers

How

• Harness lives in a separate template-claude/ folder (shipped via
  package.json files), so the default scaffold path is byte-for-byte
  unchanged unless the flag is passed.
• create --with-claude-skills copies it over the fresh scaffold.
• upgrade --with-claude-skills opts an existing plugin in, adding only
  missing files (overwrite: false) so user customizations are preserved —
  safe to re-run.
• When the harness is present, CLAUDE.md is the single agent guide: AGENTS.md
  is dropped on add, and upgrade's addMissingTemplateFiles no longer
  reintroduces AGENTS.md once CLAUDE.md exists.

Demo

Usage

headlamp-plugin create my-plugin --with-claude-skills   # new plugin
headlamp-plugin upgrade --with-claude-skills            # existing plugin

Tests

• Added create/upgrade assertions to test-headlamp-plugin.js (harness added,
  AGENTS.md dropped, no-flag upgrade doesn't reintroduce AGENTS.md).
• Documented the flag in the README.
• Verified npm pack --dry-run ships all template-claude/ files (incl. the
  .claude/ dotdir and .mcp.json).

How to test manually

Setup

Run from the headlamp-plugin package dir:

cd plugins/headlamp-plugin
npm install          # one-time, so the CLI can boot (you may have this already)
BIN="$PWD/bin/headlamp-plugin.js"
cd /tmp              # scratch area for generated plugins

1. Default create is unchanged (regression guard)

rm -rf t-default
node "$BIN" create t-default --noinstall
ls -a t-default        # expect AGENTS.md, .vscode, .gitignore, src/, package.json
test -e t-default/AGENTS.md  && echo "AGENTS.md present ✓"
test -e t-default/CLAUDE.md  && echo "CLAUDE present ✗" || echo "no CLAUDE.md ✓"
test -e t-default/.mcp.json  && echo ".mcp present ✗" || echo "no .mcp.json ✓"
test -d t-default/.claude    && echo ".claude present ✗" || echo "no .claude ✓"

Expect: AGENTS.md present; no CLAUDE.md / .mcp.json / .claude.

2. create --with-claude-skills adds the harness, drops AGENTS.md

rm -rf t-claude
node "$BIN" create t-claude --noinstall --with-claude-skills
test -e t-claude/CLAUDE.md            && echo "CLAUDE.md ✓"
test -e t-claude/.mcp.json            && echo ".mcp.json ✓"
test -e t-claude/.claude/settings.json && echo "settings.json ✓"
echo "skills: $(ls t-claude/.claude/skills | wc -l | tr -d ' ')"   # expect 10
test -e t-claude/AGENTS.md && echo "AGENTS.md present ✗" || echo "AGENTS.md dropped ✓"
test -e t-claude/src/index.tsx && test -d t-claude/.vscode && echo "default files intact ✓"

Expect: CLAUDE.md + .mcp.json + .claude/settings.json + 10 skills; no AGENTS.md; default scaffold files still present.

3. upgrade --with-claude-skills opts an existing plugin in

rm -rf t-upgrade
node "$BIN" create t-upgrade --noinstall          # starts as a default plugin
test -e t-upgrade/AGENTS.md && echo "starts with AGENTS.md ✓"

node "$BIN" upgrade t-upgrade --skip-package-updates --with-claude-skills
test -e t-upgrade/CLAUDE.md && echo "CLAUDE.md added ✓"
test -e t-upgrade/.mcp.json && echo ".mcp.json added ✓"
echo "skills: $(ls t-upgrade/.claude/skills | wc -l | tr -d ' ')"   # expect 10
test -e t-upgrade/AGENTS.md && echo "AGENTS.md present ✗" || echo "AGENTS.md dropped ✓"

--skip-package-updates keeps it fast/offline (skips npm audit/format/lint/tsc). Drop it for a full upgrade run.

Expect: harness added, AGENTS.md dropped.

4. Safety: plain upgrade (no flag) doesn't disturb a harness plugin

node "$BIN" upgrade t-upgrade --skip-package-updates    # no flag this time
test -e t-upgrade/AGENTS.md && echo "AGENTS.md reappeared ✗" || echo "AGENTS.md still gone ✓"
test -e t-upgrade/CLAUDE.md && echo "CLAUDE.md intact ✓"

Expect: AGENTS.md stays gone, CLAUDE.md intact (the guard at work).

Optional — confirm a plain upgrade on a default plugin still re-adds AGENTS.md if deleted:

rm t-default/AGENTS.md
node "$BIN" upgrade t-default --skip-package-updates
test -e t-default/AGENTS.md && echo "AGENTS.md restored on default plugin ✓"

5. --help shows the new options

node "$BIN" create --help   | grep -i claude     # shows --with-claude-skills
node "$BIN" upgrade --help  | grep -i claude     # shows --with-claude-skills

6. Packaging — the harness ships in the npm tarball

cd plugins/headlamp-plugin
npm pack --dry-run 2>/dev/null | grep template-claude   # expect 13 entries incl .claude/* and .mcp.json

7. (Optional) Full automated suite

This runs the create/upgrade assertions plus build/lint/tsc/storybook — slow (does real installs), needs network:

cd plugins/headlamp-plugin
node test-headlamp-plugin.js

8. (Optional) Real load test in Headlamp

For a true smoke test of a generated harness plugin (not just file checks):

cd /tmp/t-claude
npm install        # real install
npm start          # builds into Headlamp's dev-plugins dir; open the desktop app

Cleanup

rm -rf /tmp/t-default /tmp/t-claude /tmp/t-upgrade